.TH Canto 1 "MAN_DATE" "Version MAN_VERSION" "Canto"

.SH NAME
Canto \- An ncurses RSS reader
.SH DESCRIPTION
Canto is an RSS reader built to be flexible and highly customizable on top of python.

.SH GETTING STARTED
Canto is the client, separate from the fetcher Canto-fetch. In order to update you must invoke canto-fetch on a regular basis. Usually the way to do that is to add a line into your crontab like this:

* * * * * canto-fetch

If you're not a fan of cron, then you can add `canto-fetch -b` to your startup
scripts to have canto-fetch run as a daemon on its own.

After you have your configuration file generated, just run `canto` and it will update for you, if canto-fetch hasn't been run already.

.SH COMMAND LINE USAGE
.TP
-h/--help
Simple help

.TP
-v/--version
Print version

.TP
-u/--update
Update feeds before launching client.

.TP
-l/--list
List all configured feeds

.TP
-a/--checkall
Print number of new items.

.TP
-n/--checknew [feed]
Print number of new items in feed.

.TP
-o/--opml
Print feeds to stdout as OPML file.

.TP
-i/--import [path]
Import feeds from OPML file to your configuration.

.TP
-r/--url [URL]
Add feed at URL to your configuration.

.TP
-t/--tag [tag]
Set tag for feed added with -r

.TP
-D/--dir [path]
Set the configuration directory (default: ~/.canto/)

.TP
-C/--conf [path]
Set the configuration file (default: ~/.canto/conf)

.TP
-L/--log [path]
Set the log file (default: ~/.canto/log)

.TP
-F/--fdir [path]
Set the feed directory (default: ~/.canto/feeds)

.TP
-S /--sdir [PATH]
Set the path to execurl scripts (default ~/.canto/scripts/)

.SH INTERNAL USAGE
Within the program you can use the following (default) keys.
These can be changed in your configuration file by using the
"key" configuration option.

.TP
UP / DOWN or k / j
Select previous or next item. (next_item) (prev_item)

.TP
PGUP / PGDOWN or o / l
Goto previous or next tag. (next_tag) (prev_tag)

.TP
RIGHT / LEFT
Set item unread or read (just_unread) (just_read)

.TP
[ / ]
Cycle through defined filters (prev_filter) (next_filter)

.TP
{ / }
Cycle through defined tag filters (prev_feed_filter) (next_feed_filter)

.TP
- / =
Cycle through defined tag sorts (prev_tag_sort) (next_tag_sort)

.TP
< / >
Cycle through defined tag sets (prev_tagset) (next_tagset)

.TP
:
Goto a specific tag (order of the config) (goto_tag)

.TP
;
Goto a specific visible tag (goto_reltag)

.TP
TAB
Switch focus between list and reader (only useful with dedicated reader space)
    (switch)

.TP
h
Display this man page. (help)

.TP
Space
Read a story (reader)

.TP
g
Use the defined browser to goto the item's URL (goto)

.TP
C / V
Collapse/Uncollapse all tags (set_collapse_all) (unset_collapse_all)

.TP
c
Collapse/Uncollapse current tag (toggle_collapse_tag)

.TP
f
Inline search (inline_search)

.TP
n / p
Goto next/previous marked item (next_mark) (prev_mark)

.TP
, / .
Goto next/previous unread item (next_unread) (prev_unread)

.TP
r / u
Mark tag read/unread (tag_read) (tag_unread)

.TP
R / U
Mark all read/unread (all_read) (all_unread)

.TP
Ctrl+R
Refresh feeds (force_update)

.TP
Ctrl+L
Redraw screen (refresh)

.TP
q
Quit Canto (quit)

.SH READER USAGE
Inside the reader, there are a number of different keys. These can be changed with the "reader_key" configuration option.

.TP
UP / DOWN or k / j
Scroll up/down if content off screen (scroll_up) (scroll_down)

.TP
n / p
goto next/previous item without closing reader

.TP
l
Enumerate links (toggle_show_links)

.TP
g
Choose a link to goto (goto)

.SH CONFIGURATION
The ~/.canto/conf file is where all of the configuration is. You can start by using the example config below.

.SH EXAMPLE CONFIG
.sp 1
.nf

from canto.extra import *
import os

if os.getenv("TERM") == "linux":
    link_handler("elinks \"%u\"", text=True)
else:
    link_handler("iceweasel \"%u\"")

    # A dedicated image handler, that requires content
    # to be fetched for it.
    image_handler("xli \"%u\"", fetch=True)

    # A dedicated PDF handler (great for LtU)
    link_handler("evince \"%u\"", fetch=True, ext="pdf")

    # If we're in X, update xterm title
    # (Should work with most graphical terms)   
    select_hook = set_xterm_title
    end_hook = clear_xterm_title

def my_resize_hook(cfg):
    cfg.columns = cfg.width / 70

resize_hook = my_resize_hook

# Global filters, switch with '[' and ']'
filters=[None, show_unread]

# You can also setup keybinds to set the global filter
keys['a'] = set_filter(show_unread) 

# Similarly you can set tag filters and keybinds
# switch with '{' and '}'

default_tag_filters([None, show_unread])
keys['b'] = set_tag_filter(show_unread)

# Tag sorts can also be set with a keybind
keys['s'] = set_tag_sort(by_alpha)
keys['d'] = set_tag_sort(reverse_sort(by_len))

# Keys can be single or lists of actions
# These keys kill the current reader, go to the next
# or prev unread item and start another reader

reader_keys["."] = ["destroy","next_unread","reader"]
reader_keys[","] = ["destroy","prev_unread","reader"]

# This sets the current item as read and automatically
# continues to the next item.

keys['x'] = ["just_read","next_item"]

# Searches can be bound to keybinds as well
keys['1'] = search(".*[Ll]inux.*", regex=True)
keys['2'] = search("Obama")

# And, of course keys can be unset.
keys['Q'] = None

# This makes the reader show links by default, rather
# than the default, toggling with 'l'
keys[' '] = ["reader","toggle_show_links"]

# A whole mess of feeds with tags, and without.
# A 'None' tag will be replaced with the feeds title
# The first tag is what is show at the top of each feed by default

add("http://rss.slashdot.org/slashdot/Slashdot", tags=[None, "news"])
add("http://osnews.com/files/recent.xml", tags=[None, "news"])
add("http://www.damninteresting.com/?feed=rss2")
add("http://reddit.com/.rss", tags=["Reddit","news"])
add("http://programming.reddit.com/.rss", tags=["Proggit", "news"])

# Username / Passwords are supported for feeds protected by
# Basic or Digest passwords

add("http://feedparser.org/docs/examples/digest_auth.xml", username="test",
        password="digest")

# Tags can work without configuration, or can be customized.
# This makes the "news" tag default to showing only unread stories
# and sorting by date.

add_tag("news", filters=[show_unread], sorts=[[by_date]])

# Finally, you can set the tags shown with the tags list,
# and rotate with '<' and '>' by default.

tags = [ None, ["news"], ["Reddit", "Proggit"]]

# None will be interpreted as the default set of tags, i.e. one
# per feed.

.SH FILES
.TP
.I ~/.canto/conf
Main configuration file. For advanced usage, see the online configuration documentation: http://codezen.org/canto/config

.TP
.I ~/.canto/log
Everyday log file.

.TP
.I ~/.canto/fetchlog
Canto-fetch log file.

.TP
.I ~/.canto/feeds/
This is the directory where the stories are recorded.

.SH BUGS
None known, but it's not outside of the realm of possibility =P.  

.SH HOMEPAGE
http://codezen.org/canto

.SH AUTHOR
Jack Miller <jack@codezen.org>
